@database "render"
@master "Daten:Temporary/RenderLib/doc/autodoc/render.doc"

@Node Main "render.doc"
    @{" AddChunkyImageA() " Link "AddChunkyImageA()"}
    @{" AddHistogramA() " Link "AddHistogramA()"}
    @{" AddRGB() " Link "AddRGB()"}
    @{" AddRGBImageA() " Link "AddRGBImageA()"}
    @{" AllocRenderMem() " Link "AllocRenderMem()"}
    @{" AllocRenderVec() " Link "AllocRenderVec()"}
    @{" AllocRenderVecClear() " Link "AllocRenderVecClear()"}
    @{" ApplyAlphaChannelA() " Link "ApplyAlphaChannelA()"}
    @{" BestPen() " Link "BestPen()"}
    @{" Chunky2BitMapA() " Link "Chunky2BitMapA()"}
    @{" Chunky2RGBA() " Link "Chunky2RGBA()"}
    @{" ChunkyArrayDiversityA() " Link "ChunkyArrayDiversityA()"}
    @{" ConvertChunkyA() " Link "ConvertChunkyA()"}
    @{" CountRGB() " Link "CountRGB()"}
    @{" CreateAlphaArrayA() " Link "CreateAlphaArrayA()"}
    @{" CreateHistogramA() " Link "CreateHistogramA()"}
    @{" CreateMapEngineA() " Link "CreateMapEngineA()"}
    @{" CreatePaletteA() " Link "CreatePaletteA()"}
    @{" CreatePenTableA() " Link "CreatePenTableA()"}
    @{" CreateRMHandlerA() " Link "CreateRMHandlerA()"}
    @{" CreateScaleEngineA() " Link "CreateScaleEngineA()"}
    @{" DeleteHistogram() " Link "DeleteHistogram()"}
    @{" DeleteMapEngine() " Link "DeleteMapEngine()"}
    @{" DeletePalette() " Link "DeletePalette()"}
    @{" DeleteRMHandler() " Link "DeleteRMHandler()"}
    @{" DeleteScaleEngine() " Link "DeleteScaleEngine()"}
    @{" ExportPaletteA() " Link "ExportPaletteA()"}
    @{" ExtractAlphaChannelA() " Link "ExtractAlphaChannelA()"}
    @{" ExtractPaletteA() " Link "ExtractPaletteA()"}
    @{" FlushPalette() " Link "FlushPalette()"}
    @{" FreeRenderMem() " Link "FreeRenderMem()"}
    @{" FreeRenderVec() " Link "FreeRenderVec()"}
    @{" ImportPaletteA() " Link "ImportPaletteA()"}
    @{" InsertAlphaChannelA() " Link "InsertAlphaChannelA()"}
    @{" MapChunkyArrayA() " Link "MapChunkyArrayA()"}
    @{" MapRGBArrayA() " Link "MapRGBArrayA()"}
    @{" MixAlphaChannelA() " Link "MixAlphaChannelA()"}
    @{" MixRGBArrayA() " Link "MixRGBArrayA()"}
    @{" Planar2ChunkyA() " Link "Planar2ChunkyA()"}
    @{" QueryHistogram() " Link "QueryHistogram()"}
    @{" RenderA() " Link "RenderA()"}
    @{" RGBArrayDiversityA() " Link "RGBArrayDiversityA()"}
    @{" ScaleA() " Link "ScaleA()"}
    @{" ScaleOrdinate() " Link "ScaleOrdinate()"}
    @{" SortPaletteA() " Link "SortPaletteA()"}
    @{" TintRGBArrayA() " Link "TintRGBArrayA()"}
@EndNode

@Node "AddChunkyImageA()" "render.library/AddChunkyImageA"

@{b}   NAME@{ub}
        AddChunkyImageA - add chunky bytes to a histogram.
        AddChunkyImage  - varargs stub for AddChunkyImageA.

@{b}   SYNOPSIS@{ub}
        success = AddChunkyImageA(histogram,chunky,width,height,
        d0                        a0        a1     d0    d1     
                                  palette,taglist)
                                  a2      a3
        
        ULONG AddChunkyImageA(APTR,UBYTE *,UWORD,UWORD,
                              APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG AddChunkyImage(APTR,UBYTE *,UWORD,UWORD,
                             APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function adds an array of chunky bytes to a histogram. The
        color information contained in the chunky array and its palette
        will be stored in the histogram.

@{b}   INPUTS@{ub}
        histogram       - pointer to a histogram
        chunky          - pointer to an array of chunky bytes
        width           - width to be added [pixels]
        height          - lines to be added [rows]
        palette         - pointer to a palette
                          created with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        taglist         - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.
        
@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.

@{b}   NOTES@{ub}
        - It is not possible with this function to directly add a chunky
          array that represents a HAM color scheme. In this case you have
          to convert it to an RGB array via @{"Chunky2RGBA()" Link "Chunky2RGBA()"}, and then to
          call @{"AddRGBImageA()" Link "AddRGBImageA()"}.
           
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_ADDED message.
        
@{b}   SEE ALSO@{ub}
        @{"AddRGBImageA()" Link "AddRGBImageA()"}, @{"CreateHistogramA()" Link "CreateHistogramA()"}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "AddHistogramA()" "render.library/AddHistogramA"

@{b}   NAME@{ub}
        AddHistogramA - add a histogram to another histogram.
        AddHistogram  - varargs stub for AddHistogramA.

@{b}   SYNOPSIS@{ub}
        success = AddHistogramA(desthistogram,sourcehistogram,taglist)
        d0                      a0            a1              a2
        
        ULONG AddHistogramA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG AddHistogram(APTR,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function adds a histogram to another histogram,
        according to the following scheme:
        
        desthistogram + sourcehistogram -> desthistogram
        
        The color information contained in the source histogram
        will be added to the destination histogram.

@{b}   INPUTS@{ub}
        desthistogram       - pointer to destination histogram
        sourcehistogram     - pointer to source histogram
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_Weight (UWORD)  - multiplication factor for the
                number of representations in sourcehistogram

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.
       
@{b}   SEE ALSO@{ub}
        @{"CreateHistogramA()" Link "CreateHistogramA()"}


@EndNode

@Node "AddRGB()" "render.library/AddRGB"

@{b}   NAME@{ub}
        AddRGB - add a RGB value to a histogram.

@{b}   SYNOPSIS@{ub}
        success = AddRGB(histogram,RGB,count)
        d0               a0        d0  d1
        
        ULONG AddRGB(APTR,ULONG,ULONG)

@{b}   FUNCTION@{ub}
        This function adds a given number of representations for a
        single RGB value to a histogram.

@{b}   INPUTS@{ub}
        histogram    - pointer to a histogram
        RGB          - RGB value to be added
        count        - number of representations for that RGB value

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.

@{b}   SEE ALSO@{ub}
        @{"AddRGBImageA()" Link "AddRGBImageA()"}, @{"CreateHistogramA()" Link "CreateHistogramA()"}


@EndNode

@Node "AddRGBImageA()" "render.library/AddRGBImageA"

@{b}   NAME@{ub}
        AddRGBImageA - add an array of RGB data to a histogram.
        AddRGBImage  - varargs stub for AddRGBImageA.

@{b}   SYNOPSIS@{ub}
        success = AddRGBImageA(histogram,rgb,width,height,taglist)
        d0                     a0        a1  d0    d1     a2
        
        ULONG AddRGBImageA(APTR,ULONG *,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG AddRGBImage(APTR,ULONG *,UWORD,UWORD,tag,...,TAG_DONE) 

@{b}   FUNCTION@{ub}
        This function adds an array of RGB pixels to a histogram. The
        color information contained in the RGB array gets stored in the
        histogram.

@{b}   INPUTS@{ub}
        histogram       - pointer to a histogram
        rgb             - pointer to an array of RGB data
        width           - width to be added [pixels]
        height          - lines to be added [rows]
        taglist         - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_ADDED message.
        
@{b}   SEE ALSO@{ub}
        @{"AddRGB()" Link "AddRGB()"}, @{"CreateHistogramA()" Link "CreateHistogramA()"}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "AllocRenderMem()" "render.library/AllocRenderMem"

@{b}   NAME@{ub}
        AllocRenderMem - allocate memory from a render-memhandler.

@{b}   SYNOPSIS@{ub}
        mem = AllocRenderMem(rendermemhandler,size)
        d0                   a0               d0

        APTR AllocRenderMem(APTR, ULONG)

@{b}   FUNCTION@{ub}
        AllocRenderMem will allocate a memory block from a
        render-memhandler, or from public memory. If there is no memory
        block of the requested size available, NULL will be returned.
        You must check this return value. The request may fail at any
        time. Every call to this function must be followed by a call to
        @{"FreeRenderMem" Link "render/FreeRenderMem()"}.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to a render-memhandler, or NULL.
                           If you pass NULL, MEMF_ANY will be used.
        size             - the size of the desired block in bytes

@{b}   RESULTS@{ub}
        mem              - pointer to a block of memory, or NULL if the
                           allocation failed.

@{b}   NOTES@{ub}
        There is no real need for this function being available to you,
        except for helping you to create a smart, lean and sexy memory
        management - the idea is to enable your application and the
        library to share a particular memory pool.

@{b}   SEE ALSO@{ub}
        @{"FreeRenderMem()" Link "FreeRenderMem()"}, @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "AllocRenderVec()" "render.library/AllocRenderVec"

@{b}   NAME@{ub}
        AllocRenderVec - allocate memory from a render-memhandler, 
                         and keep track of the allocated size and
                         the memhandler itself.

@{b}   SYNOPSIS@{ub}
        mem = AllocRenderVec(rendermemhandler,size)
        d0                   a0               d0

        APTR AllocRenderVec(APTR, ULONG)

@{b}   FUNCTION@{ub}
        AllocRenderVec will allocate a memory block from a
        render-memhandler, or from public memory. If there is no memory
        block of the requested size available, NULL will be returned.
        You must check this return value. The request may fail at any
        time. Any call to this function must be followed by a call to
        @{"FreeRenderVec()" Link "FreeRenderVec()"}. AllocRenderVec() keeps track of the allocated
        size and the memhandler itself.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to a render-memhandler, or NULL.
                           If you pass NULL, MEMF_ANY will be used.
        size             - the size of the desired block in bytes

@{b}   RESULTS@{ub}
        mem              - pointer to a block of memory, or NULL
                           if the allocation failed.

@{b}   SEE ALSO@{ub}
        @{"FreeRenderVec()" Link "FreeRenderVec()"}, @{"AllocRenderVecClear()" Link "AllocRenderVecClear()"}, @{"AllocRenderMem()" Link "AllocRenderMem()"},
        @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "AllocRenderVecClear()" "render.library/AllocRenderVecClear"

@{b}   NAME@{ub}
        AllocRenderVecClear - allocate a clear block of memory from a
                              render-memhandler

@{b}   SYNOPSIS@{ub}
        mem = AllocRenderVecClear(rendermemhandler,size)
        d0                        a0               d0

        APTR AllocRenderVecClear(APTR, ULONG)

@{b}   FUNCTION@{ub}
        AllocRenderVecClear will allocate a clear memory block from a
        render-memhandler, or from public memory. If there is no memory
        block of the requested size available, NULL will be returned.
        You must check this return value. The request may fail at any
        time. Any call to this function must be followed by a call to
        @{"FreeRenderVec()" Link "FreeRenderVec()"}. AllocRenderVecClear() keeps track of the
        allocated size and the memhandler itself.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to a render-memhandler, or NULL.
                           If you pass NULL, MEMF_ANY will be used.
        size             - the size of the desired block in bytes

@{b}   RESULTS@{ub}
        mem              - pointer to a block of memory filled with
                           NULL bytes, or NULL if the allocation failed.

@{b}   SEE ALSO@{ub}
        @{"FreeRenderVec()" Link "FreeRenderVec()"}, @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"AllocRenderMem()" Link "AllocRenderMem()"},
        @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "ApplyAlphaChannelA()" "render.library/ApplyAlphaChannelA"

@{b}   NAME@{ub}
        ApplyAlphaChannelA - compose RGB array via alpha-channel.
        ApplyAlphaChannel  - varargs stub for ApplyAlphaChannelA.

@{b}   SYNOPSIS@{ub}
        ApplyAlphaChannelA(sourcearray,width,height,destarray,tags)
                           a0          d0    d1     a1        a2

        void ApplyAlphaChannelA(ULONG *,UWORD,UWORD,ULONG *,
                                struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void ApplyAlphaChannel(ULONG *,UWORD,UWORD,ULONG *,
                               tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function uses the alpha-channel information (by default taken
        from the source array) to perform a composition of the source and
        destination array. The result will be written to the
        destination array.

@{b}   INPUTS@{ub}
        sourcearray         - pointer to an ARGB array
        width               - width [pixels]
        height              - height [rows]
        destarray           - pointer to a RGB array
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the source array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the dest array [pixels].
                Default - equals to the specified width.

        RND_AlphaChannel (ULONG) - Pointer to the alpha-channel array.
                Default - equals to the pointer to the source array.

        RND_AlphaModulo (UWORD) - Pixel offset that will be used when
                proceeding from one alpha-channel value to the next [bytes].
                Default - 4.

        RND_AlphaWidth (ULONG) - Total width of the alpha-channel array
                [pixels]. Default - equals to the specified width.

@{b}   RESULTS@{ub}
        none
       
@{b}   SEE ALSO@{ub}
        @{"InsertAlphaChannelA()" Link "InsertAlphaChannelA()"}, @{"ExtractAlphaChannelA()" Link "ExtractAlphaChannelA()"}, @{"MixAlphaChannelA()" Link "MixAlphaChannelA()"}


@EndNode

@Node "BestPen()" "render.library/BestPen"

@{b}   NAME@{ub}
        BestPen - find the best matching pen.

@{b}   SYNOPSIS@{ub}
        pen = BestPen(palette,RGB)
        d0            a0      d0
        
        LONG BestPen(APTR,ULONG)

@{b}   FUNCTION@{ub}
        Determine a palette's pen number that matches best a given RGB
        value.

@{b}   INPUTS@{ub}
        palette   - palette created with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        RGB       - RGB value to find a match for

@{b}   RESULTS@{ub}
        pen       - pen number or -1 if no pen could be found.
                    (Usually this occurs when the palette is empty.)


@EndNode

@Node "Chunky2BitMapA()" "render.library/Chunky2BitMapA"

@{b}   NAME@{ub}
        Chunky2BitMapA - convert chunky data to bitplanes.
        Chunky2BitMap  - varargs stub for Chunky2BitMapA.

@{b}   SYNOPSIS@{ub}
        Chunky2BitMapA(chunky,sx,sy,width,height,bitmap,dx,dy,taglist)
                       a0     d0 d1 d2    d3     a1     d4 d5 a2
        
        void Chunky2BitMapA(UBYTE *,UWORD,UWORD,UWORD,UWORD,
                            struct @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} *,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void Chunky2BitMap(UBYTE *,UWORD,UWORD,UWORD,UWORD,
                           struct @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} *,UWORD,UWORD,tag,...,TAG_DONE) 

@{b}   FUNCTION@{ub}
        Converts an array of chunky bytes to the bitplanes associated
        with a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure. You can specify clip areas both inside
        the chunky array and the @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}. This function merges the data
        into the destination @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} if required. BMF_INTERLEAVED is also
        handled.
        
        You may only process BMF_STANDARD bitmaps with this function.

@{b}   INPUTS@{ub}
        chunky     - pointer to an array of chunky bytes
        sx         - left edge inside the chunky array [pixels]
        sy         - top edge inside the chunky array [rows]
        width      - width [pixels]
        height     - height [rows]
        bitmap     - pointer to an initialized @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure
        dx         - destination left edge inside @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} [pixels]
        dy         - destination top edge inside @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} [rows]
        taglist    - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.

@{b}   RESULTS@{ub}
        none

@{b}   IMPORTANT NOTES@{ub}
        Starting with v39, you are not allowed to assume foreign @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}
        structures being of a planar type. You may pass a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}
        structure to this function only if the BMF_STANDARD flag is set.

        Also remember to set-up your own @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure with the
        BMF_STANDARD flag if you wish to convert it with this function.
        Consider Chunky2BitMapA() being low-level. The @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure
        involved here is intended to hold planar information. Since v39,
        this is different to what graphics.library might associate with
        a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure.

        Do not use this function with @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structures that are
        actually being displayed. If you wish to transfer chunky bytes
        to visible areas, use graphics.library functions, such as
        @{"WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"}, or @{"WritePixelArray8()" Link "graphics/WritePixelArray8()"}. You may also use
        Chunky2BitMapA() followed by @{"BltBitMapRastPort()" Link "graphics/BltBitMapRastPort()"} etc.

        With a graphics card supplied, @{"WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"} can be
        hundereds times faster than Chunky2BitMapA() followed by
        @{"BltBitMapRastPort()" Link "graphics/BltBitMapRastPort()"}. If you have to provide backward
        compatibility, it is worth the effort to differenciate between
        Kick 2.x and OS 3.x. Use Chunky2BitMapA() in the first case,
        @{"WritePixelArray8()" Link "graphics/WritePixelArray8()"} in the second case, and @{"WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"}
        if the system runs under OS3.1 and is supplied with a graphics
        card.

SEE ALSO
        @{"Planar2ChunkyA()" Link "Planar2ChunkyA()"}, @{"graphics/gfx.h" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 0},
        @{"graphics.library/WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"}


@EndNode

@Node "Chunky2RGBA()" "render.library/Chunky2RGBA"

@{b}   NAME@{ub}
        Chunky2RGBA - convert an array of chunky bytes to RGB data.
        Chunky2RGB  - varargs stub for Chunky2RGBA.

@{b}   SYNOPSIS@{ub}
        success = Chunky2RGBA(chunky,width,height,rgb,palette,taglist)
        d0                    a0     d0    d1     a1  a2      a3
        
        ULONG Chunky2RGBA(UBYTE *,UWORD,UWORD,ULONG *,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG Chunky2RGB(UBYTE *,UWORD,UWORD,ULONG *,APTR,tag,...,TAG_DONE) 

@{b}   FUNCTION@{ub}
        This function converts an array of chunky bytes to RGB data.

@{b}   INPUTS@{ub}
        chunky      - pointer to an array of chunky bytes
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        rgb         - pointer to RGB destination buffer
        palette     - pointer to a palette created
                      with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_ColorMode (ULONG) - Color mode that defines how to determine
                a pixel's actual color. Valid types:

                COLORMODE_CLUT          - normal palette lookup
                COLORMODE_HAM8          - HAM8 mode palette lookup
                COLORMODE_HAM6          - HAM6 mode palette lookup
                
                Default - COLORMODE_CLUT.

        RND_LeftEdge (UWORD) - Horizontal starting position inside the
                chunky array [pixels]. This is mainly intended to allow
                the conversion of HAM clip areas.
                Default - 0.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for an additional conversion of the pen numbers.
                Default - NULL.
                Note: This is not defined for HAM modes.

        RND_LineHook (ULONG) - Pointer to a callback hook structure
                for line-related operations during conversion. This
                hook is executed once before a line is processed and
                once after it has been completed. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

@{b}   RESULTS@{ub}
        success - CONV_SUCCESS to indicate that the operation
                  succeeded. Currently, the only reason for this
                  function to fail is CONV_CALLBACK_ABORTED.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27}
          with the PMSGTYPE_LINES_CONVERTED message type.

@{b}   SEE ALSO@{ub}
        @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "ChunkyArrayDiversityA()" "render.library/ChunkyArrayDiversityA"

@{b}   NAME@{ub}
        ChunkyArrayDiversityA - calculate chunky array adaptibility
        ChunkyArrayDiversity  - varargs stub for ChunkyArrayDiversityA.

@{b}   SYNOPSIS@{ub}
        diversity = ChunkyArrayDiversityA(chunkyarray,palette,
        d0                                a0          a1
                                          width,height,taglist)
                                          d0    d1     a2

        LONG ChunkyArrayDiversityA(UBYTE *,APTR,UWORD,UWORD,
                                   struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        LONG ChunkyArrayDiversity(UBYTE *,UWORD,UWORD,
                                  tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Calculate a chunky array's adaptibility to a palette or
        mapping-engine.

@{b}   INPUTS@{ub}
        chunkyarray - pointer to an array of chunky bytes
        palette     - the chunky array's palette
        width       - width to be processed [pixels]
        height      - height to be processed [pixels]
        taglist     - pointer to an array of tagitems

@{b}   TAGS@{ub}
        RND_Palette (ULONG) - pointer to a palette. Either this or the
                RND_MapEngine argument is obligatory!

        RND_MapEngine (ULONG) - pointer to a mapping-engine. Either this
                or the RND_Palette argument is obligatory!

        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_Interleave (ULONG) - number of pixels to skip horizontally.
                Default - 0.

@{b}   RESULTS@{ub}
        diversity - an indicator for the chunky array's adaptibility
                    to the given palette or mapping-engine. 0 indicates
                    perfect adaptibility, 195075 indicates the worst case.

@{b}   IMPLEMENTATION   @{ub}
        Every color in the source array is adapted to the specified
        palette or mapping-engine. Now assume p2 is the RGB of the
        palette entry that matches best with the requested color p1.

            R
            |
            |      * p2
            |     /
            |    /
            |   / d
            |__/_________G
           /  /
          /  * p1
         /
        B

        This function sums up the diversity d² for every color in the
        source array, and divides it by the number of pixels processed:

                          k=pixels
                  1         ___
        D   =   ------   .  \\  `   d(k)²
                pixels      /__,

                             k=1

        D is returned, so what you get is the average d² for all RGB
        values that appear in the array. d² is summed up instead of d
        because it is a better indicator for most purposes.

        Best case - all pixels match perfectly: D(min) = 0.
        Worst case - all pixels are white, and the only available color
        in the palette is black: D(max) = 255²+255²+255² = 195075.
        
@{b}   EXAMPLE        @{ub}
        D indicates a palette's applicability for the given chunky
        array. You can e.g. use it to decide whether error diffusion
        should be enabled for @{"ConvertChunkyA()" Link "ConvertChunkyA()"}.

        dithermode = DITHERMODE_NONE;

        D = ChunkyArrayDiversity(sourcearray, palette, width, height, 
            RND_Palette, destpalette, RND_Interleave, 4, TAG_DONE);

        if (D > threshold)
        {
            dithermode = DITHERMODE_FS;
        }

        ConvertChunky(sourcearray, palette, width, height, destarray,
            destpalette, RND_DitherMode, dithermode, TAG_DONE);

        The interleave factor increases speed drastically. You gain a
        lot of performance if only dithering can be avoided sometimes.

@{b}   SEE ALSO@{ub}
        @{"RGBArrayDiversityA()" Link "RGBArrayDiversityA()"}


@EndNode

@Node "ConvertChunkyA()" "render.library/ConvertChunkyA"

@{b}   NAME@{ub}
        ConvertChunkyA - convert an array of chunky bytes to a new palette.
        ConvertChunky  - varargs stub for ConvertChunkyA.

@{b}   SYNOPSIS@{ub}
        success = ConvertChunkyA(source,sourcepalette,width,height,dest,        
        d0                       a0     a1            d0    d1     a2   
                                 destpalette,taglist)
                                 a3          a4
        
        ULONG ConvertChunkyA(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
                             APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG ConvertChunky(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
                            APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function converts a source array of chunky bytes to another
        chunky array, and adapts it to a new palette.

@{b}   INPUTS@{ub}
        source        - pointer to a source array of chunky bytes
        sourcepalette - pointer to the source array's palette
        width         - width to be converted [pixels]
        height        - height to be converted [rows]
        dest          - pointer to the destination chunky array
        destpalette   - pointer to the destination array's palette
        taglist       - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of source array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of dest array [pixels].
                Default - equals to the specified width.

        RND_DitherMode (UWORD) - Error diffusion mode. Valid types:

                DITHERMODE_NONE   - no error diffusion

                DITHERMODE_FS     - Floyd-Steinberg
                                    Does not handle a dither amount.

                DITHERMODE_RANDOM - Random dithering
                                    Handles RND_DitherAmount.

                DITHERMODE_EDD    - EDD dithering
                                    Does not handle a dither amount.

                Default - DITHERMODE_NONE.

        RND_DitherAmount (UWORD) - Dither intensity (0-255).
                Only valid with certain dither modes (see above).
                Default - 128.

        RND_LineHook (ULONG) - Pointer to a callback hook structure
                for line-related operations during conversion. This
                hook is executed once before a line is rendered and
                once after a line has been completed. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_OffsetColorZero (UWORD) - First pen number to appear
                in the rendered chunky image. This offset will be
                added to the palette's indices. Default - 0.
                Note: RND_PenTable overrides RND_OffsetColorZero.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.
                Note: RND_PenTable overrides RND_OffsetColorZero.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_ScaleEngine (ULONG) - Pointer to a scaling-engine.
                This scaling-engine will be used to scale the
                source data stream before it is being rendered.
                Default - NULL.

                Notes: 
                - The scaling engine's destination width and
                  height specifications override the width and
                  height arguments for @{"RenderA()" Link "RenderA()"}.
                - The scaling-engine must have been created with
                  PIXFMT_CHUNKY_CLUT.

        RND_MapEngine (ULONG) - Pointer to a mapping-engine.
                This can greatly improve performance.
                Default - NULL.
                
                Notes:
                - The mapping-engine must have been created for
                  the destination palette that is specified for
                  ConvertChunkyA().
                - With dithering enabled, you better do not
                  specify a mapping-engine which was created with
                  a link to a histogram. Accurate conversion could
                  not be guaranteed in this case.

@{b}   RESULTS@{ub}
        success - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  CONV_SUCCESS.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_CONVERTED message type.
        
@{b}   SEE ALSO@{ub}
        @{"MapChunkyArrayA()" Link "MapChunkyArrayA()"}, @{"RenderA()" Link "RenderA()"}, @{"CreatePenTableA()" Link "CreatePenTableA()"},
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "CountRGB()" "render.library/CountRGB"

@{b}   NAME@{ub}
        CountRGB     - count a RGB value in a histogram.

@{b}   SYNOPSIS@{ub}
        count = CountRGB(histogram,RGB)
        d0               a0        d0
        
        ULONG CountRGB(APTR,ULONG)

@{b}   FUNCTION@{ub}
        Counts the number of occurances for a given RGB value. The
        result may depend on the histogram's accuracy.

@{b}   INPUTS@{ub}
        histogram - pointer to a histogram

@{b}   RESULTS@{ub}
        count     - number of representations for the
                    specified RGB value.

@{b}   NOTE@{ub}
        You only get the exact result for 24bit histograms. The lower
        the resolution, the more colors are actually put together into
        one `category' of similar colors. A 24bit histogram
        differenciates 16,7 million colors, a 15bit histogram, for
        instance, only 32768.


@EndNode

@Node "CreateAlphaArrayA()" "render.library/CreateAlphaArrayA"

@{b}   NAME@{ub}
        CreateAlphaArrayA - create an alpha-channel for a RGB array.
        CreateAlphaArray  - varargs stub for CreateAlphaArrayA.

@{b}   SYNOPSIS@{ub}
        CreateAlphaArrayA(rgbarray,width,height,tags)
                          a0       d0    d1     a1

        void CreateAlphaArrayA(ULONG *,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void CreateAlphaArray(ULONG *,UWORD,UWORD,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function creates an alpha-channel for the given RGB array.
        The alpha-channel will be the difference in brightness towards
        black (0x000000), or optionally towards another RGB value.

@{b}   INPUTS@{ub}
        rgbarray            - pointer to a RGB array
        width               - width [pixels]
        height              - height [rows]
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_AlphaChannel (ULONG) - Alpha-channel destination array.
                Default - equals to rgbarray. the upmost byte in the
                RGB array is a good place for an alpha-channel, usually.

        RND_AlphaWidth (UWORD) - Total width of the alpha-channel array
                [pixels]. Default - equals to the specified width.

        RND_AlphaModulo (UWORD) - Alpha-channel pixel modulo [bytes].
                Default - 4
                
        RND_MaskRGB (ULONG) - The RGB value to compute the alpha-channel
                towards. Default - 0x000000

@{b}   RESULTS@{ub}
        none


@EndNode

@Node "CreateHistogramA()" "render.library/CreateHistogramA"

@{b}   NAME@{ub}
        CreateHistogramA - create and set up a histogram.
        CreateHistogram  - varargs stub for CreateHistogramA.

@{b}   SYNOPSIS@{ub}
        hst = CreateHistogramA(taglist)
        d0                     a1
        
        APTR CreateHistogramA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreateHistogram(tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Allocates and initializes a histogram.

@{b}   INPUTS@{ub}
        taglist - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - pointer to a render-memhandler
                created with @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}.
                Default - NULL.

        RND_HSType (UWORD) - Type of histogram. Valid types:

                HSTYPE_12BIT            - 12bit dynamic histogram
                HSTYPE_15BIT            - 15bit dynamic histogram
                HSTYPE_18BIT            - 18bit dynamic histogram
                HSTYPE_21BIT            - 21bit dynamic histogram
                HSTYPE_24BIT            - 24bit dynamic histogram
                HSTYPE_12BIT_TURBO      - 12bit tabular histogram
                HSTYPE_15BIT_TURBO      - 15bit tabular histogram
                HSTYPE_18BIT_TURBO      - 18bit tabular histogram

                Default - HSTYPE_15BIT_TURBO.

@{b}   RESULTS@{ub}
        histogram - pointer to a histogram ready for usage,
                    or NULL if something went wrong.

@{b}   SEE ALSO@{ub}
        @{"DeleteHistogram()" Link "DeleteHistogram()"}, @{"QueryHistogram()" Link "QueryHistogram()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "CreateMapEngineA()" "render.library/CreateMapEngineA"

@{b}   NAME@{ub}
        CreateMapEngineA - create a mapping-engine.
        CreateMapEngine - varargs stub for CreateMappingEngineA.

@{b}   SYNOPSIS@{ub}
        engine = CreateMapEngineA(palette,taglist)
        d0                        a0       a1

        ULONG CreateMapEngineA(APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG CreateMapEngine(APTR,tag,...,TAG_DONE)

  FUNCTION
        This function will create and prepare a mapping-engine for
        usage. Mapping-engines are highly optimized low-level conversion
        units for rendering to a specific palette.

        Mapping-engines are immediately dependent from a palette, and
        they may be additionally coupled with a histogram. In the latter
        case, mapping-engines adapt only RGB values that can be found in
        the histogram.

        Mapping-engines do not incorporate the contents of their
        palettes and histograms. They are getting notified, and they
        automagically update themselves when needed. This update takes
        place only on demand, i.e. whenever you pass a mapping-engine to
        a function. The mapping-engine checks if any changes applied to
        the palette or histogram, and it reconstructs itself. The
        palette's pen-adaption buffers are updated as well - palettes
        and mapping-engines are just good friends.

@{b}   INPUTS@{ub}
        palette       - pointer to a palette
        taglist       - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - Pointer to a render-memhandler.
                This will be used for the mapping-engine's
                buffers. Default - The palette's memhandler.
   
        RND_Histogram (ULONG) - Pointer to a histogram.
                The histogram must be of a HSTYPE_..._TURBO type,
                and have the same resolution as the palette.
                Default - none.

@{b}   RESULTS@{ub}
        engine - pointer to a mapping-engine ready for usage,
                 or NULL if something went wrong.

@{b}   NOTES@{ub}
        You must free a mapping-engine before you @{"DeletePalette()" Link "DeletePalette()"} the
        palette it is dependent from. The same applies for the
        histogram.

@{b}   SEE ALSO@{ub}
        @{"DeleteMapEngine()" Link "DeleteMapEngine()"}, @{"MapRGBArrayA()" Link "MapRGBArrayA()"}, @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "CreatePaletteA()" "render.library/CreatePaletteA"

@{b}   NAME@{ub}
        CreatePaletteA - create a palette.
        CreatePalette  - vararg stub for CreatePaletteA.

@{b}   SYNOPSIS@{ub}
        palette = CreatePaletteA(taglist)
        d0                       a1
        
        APTR CreatePaletteA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreatePalette(tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function creates and initializes a palette that can hold up
        to 256 color entries.

@{b}   INPUTS@{ub}
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_HSType (ULONG) - the palette's resolution. Palette adaption
                accuracy and memory consumption depend on this constant.
                A palette's resolution is specified analogously to a
                histogram's resolution. Valid types:

                HSTYPE_12BIT
                HSTYPE_15BIT
                HSTYPE_18BIT

                Default - HSTYPE_15BIT.

        RND_RMHandler (ULONG) - pointer to a render-memhandler that was
                created with CreateRMHandler(). Default - NULL.
        
@{b}   RESULTS@{ub}
        palette  - a palette ready for usage,
                   or NULL if something went wrong.

@{b}   SEE ALSO@{ub}
        @{"DeletePalette()" Link "DeletePalette()"}, @{"ImportPaletteA()" Link "ImportPaletteA()"}, @{"ExportPaletteA()" Link "ExportPaletteA()"}, 
        @{"ExtractPaletteA()" Link "ExtractPaletteA()"}, @{"FlushPalette()" Link "FlushPalette()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "CreatePenTableA()" "render.library/CreatePenTableA"

@{b}   NAME@{ub}
        CreatePenTableA - create a pen conversion table.
        CreatePenTable  - varargs stub for CreatePenTableA.

@{b}   SYNOPSIS@{ub}
        CreatePenTableA(chunky,oldpalette,width,height,newpalette,
                        a0     a1         d0    d1     a2
                        pentab,taglist)
                        a3     a4
        
        void CreatePenTableA(UBYTE *,APTR,UWORD,UWORD,APTR,
                             UBYTE *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void CreatePenTable(UBYTE *,APTR,UWORD,UWORD,APTR,
                            UBYTE *,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function creates a table for the conversion of a particular
        array of chunky bytes. It scans through the chunky array, adapts
        the found palette entries to a new palette, and generates an
        output table of 256 UBYTEs. The resulting table is handled as
        follows:

        new_pen_number = pentab[old_pen_number]
        
@{b}   INPUTS@{ub}
        chunky      - pointer to an array of chunky bytes
        oldpalette  - pointer to the original palette
        width       - width to be processed [pixels]
        height      - height to be processed [rows]
        newpalette  - pointer to a palette to be adapted to
        pentab      - pointer to the destination table
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.
        
@{b}   RESULTS@{ub}
        none
        
@{b}   NOTES@{ub}
        The destination table is assumed to have 256 entries,
        with no respect to what color indices actually occur in
        the chunky array.

@{b}   SEE ALSO@{ub}
        @{"ConvertChunkyA()" Link "ConvertChunkyA()"}, @{"CreatePaletteA()" Link "CreatePaletteA()"}


@EndNode

@Node "CreateRMHandlerA()" "render.library/CreateRMHandlerA"

@{b}   NAME@{ub}
        CreateRMHandlerA - Create and set up a memory handler.
        CreateRMHandler  - varargs stub for CreateRMHandlerA.

@{b}   SYNOPSIS@{ub}
        rmh = CreateRMHandlerA(taglist)
        d0                     a1
        
        APTR CreateRMHandlerA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreateRMHandler(tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function allocates and initializes a render-memhandler.
        This is a custom memory resource manager for histograms,
        rendering, palettes, and many other render.library
        objects and functions. You may use a render-memhandler for your
        own purposes, too.

        A render-memhandler helps to avoid memory fragmentation as well
        as extreme stressing of the system's public memory lists.
        Private memory management is supported as well as v39 exec pools
        and common public memory. Future versions might provide more
        types of memory management.

@{b}   INPUTS@{ub}
        taglist - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_MemType (UWORD) - type of memory management. Valid types:

                RMHTYPE_POOL            - v39 exec dynamic pool
                RMHTYPE_PRIVATE         - you supply a private memory pool
                RMHTYPE_PUBLIC          - use common public memory

                Default - RMHTYPE_PUBLIC.

        RND_MemBlock (ULONG) - pointer to a block of memory
                used for private memory management. This tag
                is obligatory if you specify RMHTYPE_PRIVATE
                and is ignored otherwise. 
                Default - none.

        RND_MemSize (ULONG) - size of the memory block used
                for private memory management. This tag is
                obligatory if you specify RMHTYPE_PRIVATE
                and is ignored otherwise. 
                Default - none.

        RND_MemFlags (ULONG) - memory flags, as defined in
                @{"exec/memory.h" Link "TEXT_INCLUDE:exec/memory.h/Main" 0}. These are ignored for
                RMHTYPE_PRIVATE. Default - MEMF_ANY.

@{b}   RESULTS@{ub}
        rmh - a render-memhandler ready for usage, or NULL if
              something went wrong.

@{b}   NOTES@{ub}
        You must check for the presence of exec v39 before you create a
        memhandler with RMHTYPE_POOL specified.

@{b}   SEE ALSO@{ub}
        @{"AllocRenderMem()" Link "AllocRenderMem()"}, @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"DeleteRMHandler()" Link "DeleteRMHandler()"},
        @{"exec.library/CreatePool()" Link "exec/CreatePool()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"exec/memory.h" Link "TEXT_INCLUDE:exec/memory.h/Main" 0}


@EndNode

@Node "CreateScaleEngineA()" "render.library/CreateScaleEngineA"

@{b}   NAME@{ub}
        CreateScaleEngineA - Create a scaling-engine.
        CreateScaleEngine  - varargs stub for CreateScaleEngineA.

@{b}   SYNOPSIS@{ub}
        scaleengine = CreateScaleEngineA(sourcewidth,sourceheight,
        d0                               d0          d1           
                                         destwidth,destheight,taglist)
                                         d2        d3         a1
        
        APTR CreateScaleEngineA(UWORD,UWORD,UWORD,
                                UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreateScaleEngine(UWORD,UWORD,UWORD,
                               UWORD,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Allocates and initializes a scaling-engine for a specific set of
        scaling parameters. Once set up, a scaling-engine is highly
        optimized for its particular parameter specifications.

@{b}   INPUTS@{ub}
        sourcewidth  - source width [pixels]
        sourceheight - source height [rows]
        destwidth    - destination width [pixels]
        destheight   - destination height [rows]
        taglist      - pointer to an array of tag items

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - pointer to a render-memhandler,
                such as created with @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}.
                Default - NULL.

        RND_PixelFormat (ULONG) - Type of data to process.
                Currently defined are PIXFMT_CHUNKY_CLUT
                and PIXFMT_0RGB_32. Default - PIXFMT_CHUNKY_CLUT.

        RND_Coordinates (ULONG) - Pointer to an array of coordinates
                for texturemapped scaling. This array consists of
                4 WORD pairs of x/y coordinates each. The array forms
                a trapezoid inside the destination buffer for the source
                array being mapped to. Any parameters are valid, since
                clipping is fully implemented. Default - NULL.

@{b}   RESULTS@{ub}
        engine - a scaling-engine ready for usage, or NULL
                 if something went wrong.

@{b}   SEE ALSO@{ub}
        @{"DeleteScaleEngine()" Link "DeleteScaleEngine()"}, @{"ScaleA()" Link "ScaleA()"}


@EndNode

@Node "DeleteHistogram()" "render.library/DeleteHistogram"

@{b}   NAME@{ub}
        DeleteHistogram - dispose a histogram.

@{b}   SYNOPSIS@{ub}
        DeleteHistogram(histogram)
                        a0

        void DeleteHistogram(APTR)

@{b}   FUNCTION@{ub}
        Removes a histogram and frees all associated memory.

@{b}   INPUTS@{ub}
        histogram   - pointer to a histogram
                      Passing a NULL pointer is safe.

@{b}   RESULTS@{ub}
        none


@EndNode

@Node "DeleteMapEngine()" "render.library/DeleteMapEngine"

@{b}   NAME@{ub}
        DeleteMapEngine - dispose a mapping-engine.

@{b}   SYNOPSIS@{ub}
        DeleteMapEngine(engine)
                        a0

        void DeleteMapEngine(APTR)

@{b}   FUNCTION@{ub}
        Removes a mapping-engine and frees all associated memory.

@{b}   INPUTS@{ub}
        engine   - pointer to a mapping-engine

@{b}   NOTES@{ub}
        You must free mapping-engines before you delete the
        palettes and histograms they're dependent from.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        CreateMapEngine()


@EndNode

@Node "DeleteRMHandler()" "render.library/DeleteRMHandler"

@{b}   NAME@{ub}
        DeleteRMHandler - free a render-memhandler.

@{b}   SYNOPSIS@{ub}
        DeleteRMHandler(rendermemhandler)
                        a0

        void DeleteRMHandler(APTR)

@{b}   FUNCTION@{ub}
        DeleteRMHandler() will remove and free a previously created
        render-memhandler. That does not imply that any outstanding
        memory will be returned to the system or to whatever memory
        ressources. You are responsible for freeing each memory block
        that you have allocated from a render-memhandler.

@{b}   INPUTS@{ub}
        render-memhandler - a render-memhandler to be deleted.

@{b}   RESULTS@{ub}
        none

@{b}   NOTES@{ub}
        You are not allowed to call DeleteRMHandler() before every
        single byte has been returned to the memhandler.

@{b}   SEE ALSO@{ub}
        @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "DeletePalette()" "render.library/DeletePalette"

@{b}   NAME@{ub}
        DeletePalette - dispose a palette.

@{b}   SYNOPSIS@{ub}
        DeletePalette(palette)
                      a0

        void DeletePalette(APTR)

@{b}   FUNCTION@{ub}
        This function deletes a palette and frees all
        associated memory.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"FlushPalette()" Link "FlushPalette()"}


@EndNode

@Node "DeleteScaleEngine()" "render.library/DeleteScaleEngine"

@{b}   NAME@{ub}
        DeleteScaleEngine - dispose a scaling-engine.

@{b}   SYNOPSIS@{ub}
        DeleteScaleEngine(engine)
                          a0

        void DeleteScaleEngine(APTR)

@{b}   FUNCTION@{ub}
        Deletes a scaling-engine and frees all associated memory.

@{b}   INPUTS@{ub}
        engine   - a scaling-engine to be removed

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}


@EndNode

@Node "ExportPaletteA()" "render.library/ExportPaletteA"

@{b}   NAME@{ub}
        ExportPaletteA - export a palette.
        ExportPalette  - varargs stub for ExportPaletteA.

@{b}   SYNOPSIS@{ub}
        ExportPaletteA(palette,buffer,taglist)
                       a0      a1     a2
        
        ExportPaletteA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ExportPalette(APTR,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function exports a palette (or a part of it)
        to a colortable.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        buffer    - pointer to a destination buffer
        taglist   - pointer to an array of tag items

@{b}   TAGS@{ub}
        RND_PaletteFormat (ULONG) - format of the color table
                to be exported. Valid types:

                PALFMT_RGB32    - ULONG red,green,blue
                PALFMT_RGB8     - ULONG 0x00rrggbb
                PALFMT_RGB4     - UWORD 0xrgb

                Default - PALFMT_RGB8.

        RND_FirstColor (ULONG) - first color entry to export.
                Default - 0.
        
        RND_NumColors (ULONG) - number of colors to export.
                Default - the number of colors inside the palette.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"ImportPaletteA()" Link "ImportPaletteA()"}


@EndNode

@Node "ExtractAlphaChannelA()" "render.library/ExtractAlphaChannelA"

@{b}   NAME@{ub}
        ExtractAlphaChannelA - extract alpha-channel from an ARGB array.
        ExtractAlphaChannel  - varargs stub for ExtractAlphaChannelA.

@{b}   SYNOPSIS@{ub}
        ExtractAlphaChannelA(argbarray,width,height,chunkyarray,tags)
                             a0       d0    d1     a1          a2

        void ExtractAlphaChannelA(ULONG *,UWORD,UWORD,UBYTE *,
                                  struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void ExtractAlphaChannel(ULONG *,UWORD,UWORD,UBYTE *,
                                 tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function extracts the alpha-channel mask from an ARGB array
        and writes it to an array of chunky bytes.

@{b}   INPUTS@{ub}
        argbarray           - pointer to an ARGB array
        width               - width [pixels]
        height              - height [rows]
        chunkyarray         - pointer to an array of chunky bytes
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the ARGB array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

@{b}   RESULTS@{ub}
        none
       
@{b}   SEE ALSO@{ub}
        @{"InsertAlphaChannelA()" Link "InsertAlphaChannelA()"}, @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}


@EndNode

@Node "ExtractPaletteA()" "render.library/ExtractPaletteA"

@{b}   NAME@{ub}
        ExtractPaletteA - extract a palette from a histogram.
        ExtractPalette  - varargs stub for ExtractPaletteA.

@{b}   SYNOPSIS@{ub}
        success = ExtractPaletteA(histogram,palette,numcolors,taglist)
        d0                        a0        a1      d0        a2
        
        ULONG ExtractPaletteA(APTR,ULONG *,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG ExtractPalettA(APTR,ULONG *,UWORD,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function extracts a given number of colors from a
        histogram and stores it in a palette.

@{b}   INPUTS@{ub}
        histogram - pointer to a histogram
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        numcolors - number of entries to extract
        taglist   - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - @{"Custom" Link "TEXT_INCLUDE:hardware/custom.h/Main" 24} memory handler created with
                @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}. This is used to handle intermediate
                buffers during quantization.
                Default - The histogram's memory handler.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_RGBWeight (ULONG) - R/G/B quantization factors.
                They form a relative measurement between the R/G/B
                components, defining what color components should be
                preferred when the histogram gets decomposed.
                Default - 0x010101 (all components are treat equally).

        RND_ColorMode (ULONG) - Color mode that defines how to determine
                a pixel's actual color. Currently this tag should only be
                set to COLORMODE_HAM6 if you extract a palette for the
                use with a HAM6 image. 
                Default - COLORMODE_CLUT.

        RND_FirstColor (ULONG) - first color entry inside the palette
                that will be used for the extracted colors. See also
                @{"ImportPaletteA()" Link "ImportPaletteA()"} for further details. Default - 0.

        RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
                that you want to dispose the current palette and
                create a new one. If set to FALSE, the new color entries
                are merged to the existing palette. Default - TRUE.

@{b}   RESULTS@{ub}
        success - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  EXTP_SUCCESS.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27}
          with the PMSGTYPE_COLORS_CHOSEN message type.

@{b}   SEE ALSO@{ub}
        @{"CreateHistogramA()" Link "CreateHistogramA()"}, @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"ImportPaletteA()" Link "ImportPaletteA()"},
        @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "FlushPalette()" "render.library/FlushPalette"

@{b}   NAME@{ub}
        FlushPalette - flush all buffers from a palette.

@{b}   SYNOPSIS@{ub}
        FlushPalette(palette)
                     a0

        void FlushPalette(APTR)

@{b}   FUNCTION@{ub}
        This function flushes all buffers that might be
        associated with a palette.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette that was
                    created with @{"CreatePaletteA()" Link "CreatePaletteA()"}

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"DeletePalette()" Link "DeletePalette()"}


@EndNode

@Node "FreeRenderMem()" "render.library/FreeRenderMem"

@{b}   NAME@{ub}
        FreeRenderMem - return memory to a render-memhandler.

@{b}   SYNOPSIS@{ub}
        FreeRenderMem(rendermemhandler,mem,size)
                      a0               a1  d0

        void FreeRenderMem(APTR,APTR,ULONG)

@{b}   FUNCTION@{ub}
        Free a block of memory that was allocated with
        @{"AllocRenderMem()" Link "AllocRenderMem()"}.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to the render-memhandler the block
                           has been allocated from
        mem              - pointer to the memory block to be returned
        size             - size of that memory block [bytes]

@{b}   RESULTS@{ub}
        NONE

@{b}   SEE ALSO@{ub}
        @{"AllocRenderMem()" Link "AllocRenderMem()"}, @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "FreeRenderVec()" "render.library/FreeRenderVec"

@{b}   NAME@{ub}
        FreeRenderVec - return memory to a render-memhandler.

@{b}   SYNOPSIS@{ub}
        FreeRenderVec(mem)
                      a0

        void FreeRenderVec(APTR)

@{b}   FUNCTION@{ub}
        Free a block of memory that was allocated with @{"AllocRenderVec()" Link "AllocRenderVec()"}.

@{b}   INPUTS@{ub}
        mem - pointer to a memory block
              to be returned to its render-memhandler.
              Passing a NULL pointer is safe.

@{b}   RESULTS@{ub}
        NONE

@{b}   SEE ALSO@{ub}
        @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"DeleteRMHandler()" Link "DeleteRMHandler()"}


@EndNode

@Node "ImportPaletteA()" "render.library/ImportPaletteA"

@{b}   NAME@{ub}
        ImportPaletteA - import a palette.
        ImportPalette  - varargs stub for ImportPaletteA.

@{b}   SYNOPSIS@{ub}
        ImportPaletteA(palette,table,entries,taglist)
                       a0      a1    d0      a2
        
        ImportPaletteA(APTR,APTR,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ImportPalette(APTR,APTR,UWORD,tag,...,TAG_DONE)
        
@{b}   FUNCTION@{ub}
        This function imports entries from a color table (or from a
        palette) to a palette. You are allowed to import multiple times.
        When doing so, entries will be overwritten (not inserted). The
        palette automatically grows to the required number of entries.
        @{"Remember" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 1430} to neither import more than 256 entries nor beyond the
        256th entry.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        table     - pointer to a source color table
                    (or a render.library palette)
        entries   - number of color entries to import
        taglist   - pointer to an array of tag items

@{b}   TAGS@{ub}
        RND_PaletteFormat (ULONG) - format of the color table
                to be imported. Valid types:

                PALFMT_RGB32    - ULONG red,green,blue
                PALFMT_RGB8     - ULONG 0x00rrggbb
                PALFMT_RGB4     - UWORD 0xrgb
                PALFMT_PALETTE  - another palette

                Default - PALFMT_RGB8.

        RND_FirstColor (ULONG) - first color entry inside the
                palette to import to. Default - 0.

        RND_EHBPalette (ULONG) - tag to indicate whether the
                imported colors should be interpreted as for an
                Extra-Halfbrite picture. Default - FALSE.

        RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
                that you want to dispose the current palette and
                import a new one. If set to FALSE, the palette is
                merged. Default - TRUE.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"ExportPaletteA()" Link "ExportPaletteA()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "InsertAlphaChannelA()" "render.library/InsertAlphaChannelA"

@{b}   NAME@{ub}
        InsertAlphaChannelA - insert a alpha-channel mask to a RGB array.
        InsertAlphaChannel  - varargs stub for InsertAlphaChannelA.

@{b}   SYNOPSIS@{ub}
        InsertAlphaChannelA(chunkyarray,width,height,rgbarray,tags)
                            a0          d0    d1     a1       a2

        void InsertAlphaChannelA(UBYTE *,UWORD,UWORD,ULONG *,
                                 struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void InsertAlphaChannel(UBYTE *,UWORD,UWORD,ULONG *,
                                tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function inserts an array of chunky bytes to a RGB array.
        The resulting ARGB array can then be used for alpha-channel
        operations, such as provided with @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}.

@{b}   INPUTS@{ub}
        chunkyarray         - pointer to an array of chunky bytes
        width               - width [pixels]
        height              - height [rows]
        rgbarray            - pointer to a RGB array
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the rgb array [pixels].
                Default - equals to the specified width.

@{b}   RESULTS@{ub}
        none
       
@{b}   SEE ALSO@{ub}
        @{"ExtractAlphaChannelA()" Link "ExtractAlphaChannelA()"}, @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}


@EndNode

@Node "MapChunkyArrayA()" "render.library/MapChunkyArrayA"

@{b}   NAME@{ub}
        MapChunkyArrayA - remap a chunky array.
        MapChunkyArray  - varargs stub for MapChunkyArrayA.

@{b}   SYNOPSIS@{ub}
        success = MapChunkyArrayA(engine,sourcearray,palette,width,
        d0                        a0     a1          a2      d0    
                                  height,destarray,taglist)
                                  d1     a3        a4

        ULONG MapChunkyArrayA(APTR,UBYTE *,APTR,UWORD,UWORD,UBYTE *,
                              struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        ULONG MapChunkyArray(APTR,UBYTE *,APTR,UWORD,UWORD,UBYTE *,
                             tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        MapChunkyArrayA() maps an array of chunky bytes to another
        chunky array.

@{b}   INPUTS@{ub}
        engine      - pointer to a mapping-engine created
                      with @{"CreateMapEngineA()" Link "CreateMapEngineA()"}
        sourcearray - pointer to source array of chunky pixels
        palette     - pointer to source array's palette
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        destarray   - pointer to the destination chunky array
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.

@{b}   RESULTS@{ub}
        success - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  CONV_SUCCESS.

@{b}   NOTES@{ub}
        This function is considered low-level. Much more functionality
        is provided with @{"ConvertChunkyA()" Link "ConvertChunkyA()"}. Mapping-engines may also be
        passed to @{"ConvertChunkyA()" Link "ConvertChunkyA()"}, and MapChunkyArrayA() is only slightly
        faster in this case. @{"ConvertChunkyA()" Link "ConvertChunkyA()"} is preferable under most
        circumstances. If you need to remap lots of tiny images, you
        might prefer MapChunkyArrayA(), since it has got very few overhead.

@{b}   SEE ALSO@{ub}
        @{"ConvertChunkyA()" Link "ConvertChunkyA()"}, @{"MapRGBArrayA()" Link "MapRGBArrayA()"}, @{"CreateMapEngineA()" Link "CreateMapEngineA()"}


@EndNode

@Node "MapRGBArrayA()" "render.library/MapRGBArrayA"

@{b}   NAME@{ub}
        MapRGBArrayA - map an RGB array to chunky bytes.
        MapRGBArray  - varargs stub for MapRGBArrayA.

@{b}   SYNOPSIS@{ub}
        success = MapRGBArrayA(engine,rgbarray,width,height,chunky,taglist)
        d0                     a0     a1       d0    d1     a2     a3

        ULONG MapRGBArrayA(APTR,ULONG *,UWORD,UWORD,UBYTE *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        ULONG MapRGBArray(APTR,ULONG *,UWORD,UWORD,UBYTE *,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        MapRGBArrayA() maps an array of RGB data to a chunky array.

@{b}   INPUTS@{ub}
        engine      - pointer to a mapping-engine created
                      with @{"CreateMapEngineA()" Link "CreateMapEngineA()"}
        rgbarray    - pointer to an array of RGB pixels
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        chunky      - pointer to the destination array
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.

@{b}   RESULTS@{ub}
        success - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  CONV_SUCCESS.

@{b}   NOTES@{ub}
        - Do not use MapRGBArrayA() with ARGB (A=alpha-channel) data.
          The upper byte must be set to zero!
        - This function is considered low-level. Much more functionality
          is provided with @{"RenderA()" Link "RenderA()"}. Mapping-engines may also be passed
          to @{"RenderA()" Link "RenderA()"}, and MapRGBArrayA() is only slightly faster in this
          case. @{"RenderA()" Link "RenderA()"} is preferable under most circumstances. If you
          need to render lots of tiny images, you might prefer
          MapRGBArrayA(), since it has got few overhead.

@{b}   SEE ALSO@{ub}
        @{"RenderA()" Link "RenderA()"}, @{"MapChunkyArrayA()" Link "MapChunkyArrayA()"}, @{"CreateMapEngineA()" Link "CreateMapEngineA()"}


@EndNode

@Node "MixAlphaChannelA()" "render.library/MixAlphaChannelA"

@{b}   NAME@{ub}
        MixAlphachannelA - mix two arrays via alpha-channels.
        MixAlphachannel  - varargs stub for MixAlphachannelA.

@{b}   SYNOPSIS@{ub}
        MixAlphachannelA(sourcearray1,sourcearray2,width,height,destarray,
                         a0           a1           d0    d1     a2
                         tags)
                         a3

        void MixAlphachannelA(ULONG *,ULONG *,UWORD,UWORD,ULONG *,
                              struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void MixAlphachannel(ULONG *,ULONG*,UWORD,UWORD,ULONG *,
                             tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function does a 'weighted' alpha-channel composition of
        two RGB arrays and writes the result to a third RGB array.
        You may optionally disable one or both alpha-channel sources,
        in the latter case a 1:1 mix (without alpha-channel) will be
        performed.

@{b}   INPUTS@{ub}
        sourcearray1        - pointer to an RGB array, source
        sourcearray2        - pointer to an RGB array, source
        width               - width [pixels]
        height              - height [rows]
        destarray           - pointer to an RGB array, destination
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of sourcearray1 [pixels].
                Default - equals to the specified width.

        RND_SourceWidth2 (UWORD) - Total width of sourcearray2 [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of destarray [pixels].
                Default - equals to the specified width.

        RND_AlphaChannel (ULONG) - Pointer to an alpha-channel array
                for sourcearray1. This may be NULL. Default - equals
                to sourcearray1.
       
        RND_AlphaWidth (UWORD) - Total width of the first alpha-channel
                array [pixels]. Default - equals to RND_SourceWidth.

        RND_AlphaModulo (UWORD) - Alpha-channel pixel modulo for the
                first alpha-channel array [bytes]. Default - 4

        RND_AlphaChannel2 (ULONG) - Pointer to an alpha-channel array
                for sourcearray2. This may be NULL. Default - equals
                to sourcearray2.

        RND_AlphaWidth2 (UWORD) - Total width of the second alpha-channel
                array [pixels]. Default - equals to RND_SourceWidth2.

        RND_AlphaModulo2 (UWORD) - Alpha-channel pixel modulo for the
                second alpha-channel array [bytes]. Default - 4
                
@{b}   RESULTS@{ub}
        none

@{b}   NOTES@{ub}
        this function is much more generalized than @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}
        and @{"MixRGBArrayA()" Link "MixRGBArrayA()"}, but it has got more overhead and might be
        noticably slower. read the appropriate autodoc sections to see
        if one of the above mentioned functions suffice for your particular
        purpose.

@{b}   SEE ALSO@{ub}
        @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}, @{"MixRGBArrayA()" Link "MixRGBArrayA()"}, @{"InsertAlphaChannelA()" Link "InsertAlphaChannelA()"},
        @{"ExtractAlphaChannelA()" Link "ExtractAlphaChannelA()"}


@EndNode

@Node "MixRGBArrayA()" "render.library/MixRGBArrayA"

@{b}   NAME@{ub}
        MixRGBArrayA - mix two RGB arrays.
        MixRGBArray  - varargs stub for MixRGBArrayA.

@{b}   SYNOPSIS@{ub}
        MixRGBArrayA(sourcearray,width,height,destarray,ratio,tags)
                     a0          d0    d1     a1        d2    a2

        void MixRGBArrayA(ULONG *,UWORD,UWORD,ULONG *,UWORD,
                          struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void MixRGBArray(ULONG *,UWORD,UWORD,ULONG *,UWORD,
                         tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function mixes sourcearray and destarray and writes
        the result to destarray. Unlike @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}, this
        function does not use any alpha-channel information.

@{b}   INPUTS@{ub}
        sourcearray         - pointer to an ARGB array
        width               - width [pixels]
        height              - height [rows]
        destarray           - pointer to a RGB array
        ratio               - mix ratio (0...255)
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the source array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the dest array [pixels].
                Default - equals to the specified width.

@{b}   RESULTS@{ub}
        none
       
@{b}   SEE ALSO@{ub}
        @{"ApplyAlphaChannelA()" Link "ApplyAlphaChannelA()"}


@EndNode

@Node "Planar2ChunkyA()" "render.library/Planar2ChunkyA"

@{b}   NAME@{ub}
        Planar2ChunkyA - convert bitplane data to chunky bytes.
        Planar2Chunky  - varargs stub for Planar2ChunkyA.

@{b}   SYNOPSIS@{ub}
        Planar2ChunkyA(planetab,bytewidth,rows,depth,bytesperrow,
                       a0       d0        d1   d2    d3
                       chunkybuffer,taglist)
                       a1           a2

        void Planar2ChunkyA(PLANEPTR *,UWORD,UWORD,UWORD,UWORD,
                            UBYTE *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void Planar2Chunky(PLANEPTR *,UWORD,UWORD,UWORD,UWORD
                            UBYTE *,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function converts raw bitplane-oriented (planar) graphics
        to an array of chunky bytes.

@{b}   INPUTS@{ub}
        planetab    - pointer to a table of planepointers
        bytewidth   - width [bytes]. This must be an even number.
        rows        - height [rows]
        depth       - number of bitplanes in planetab
        bytesperrow - total bytes per row in the source bitplanes.
                      This must be an even number. If you convert
                      interleaved bitplanes, multiply by depth.
        chunky      - pointer to the destination chunky buffer
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_DestWidth (UWORD) - Total width of chunky array [pixels].
                Default - equals to bytewidth * 8.

                You are explicitely allowed to use a destwidth that is
                smaller than bytewidth * 8 pixels.
                
                Important note:
                If you specify this tag, you must _still_ supply a
                chunky buffer of at least bytewidth * 8 * rows bytes.

@{b}   NOTES@{ub}
        Starting with v39, you are not allowed to assume foreign @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}
        structures being of a planar type. Before you grab a table of
        planepointers out of an unknown @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure and pass it to
        this function, you have to check for the presence of the
        BMF_STANDARD flag.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"Chunky2BitMapA()" Link "Chunky2BitMapA()"}, @{"graphics/gfx.h" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 0}


@EndNode

@Node "QueryHistogram()" "render.library/QueryHistogram"

@{b}   NAME@{ub}
        QueryHistogram - query a histogram parameter.

@{b}   SYNOPSIS@{ub}
        value = QueryHistogram(histogram,tag)
        d0                     a0        d0
        
        ULONG QueryHistogram(APTR,Tag)

@{b}   FUNCTION@{ub}
        Query one of a histogram's specifications
        via @{"Tag" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 29} parameter.

@{b}   INPUTS@{ub}
        histogram - pointer to a histogram
        tag       - @{"Tag" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 29} to be queried

@{b}   TAGS@{ub}
        RND_NumColors (ULONG) -
                the number of different colors inside the histogram

        RND_NumPixels (ULONG) -
                the number of pixels that have been added to the
                histogram

        RND_RMHandler (ULONG) -
                the histogram's render-memhandler

        RND_HSType (UWORD) -
                the histogram's type

@{b}   RESULTS@{ub}
        value    - the queried parameter

@{b}   SEE ALSO@{ub}
        @{"CreateHistogramA()" Link "CreateHistogramA()"}


@EndNode

@Node "RenderA()" "render.library/RenderA"

@{b}   NAME@{ub}
        RenderA - render an array of RGB data to chunky bytes.
        Render  - varargs stub for RenderA.

@{b}   SYNOPSIS@{ub}
        success = RenderA(rgb,width,height,chunky,palette,taglist)
        d0                a0  d0    d1     a1     a2      a3
        
        ULONG RenderA(ULONG *,UWORD,UWORD,UBYTE *,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG Render(ULONG *,UWORD,UWORD,UBYTE *,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Render an array of RGB data to an array of chunky bytes.

@{b}   INPUTS@{ub}
        rgb         - pointer to an array of RGB pixels
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        chunky      - pointer to the destination array
        palette     - pointer to a palette to be rendered to
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_ColorMode (ULONG) - Color mode that defines how to determine
                a pixel's actual color. Valid types:

                COLORMODE_CLUT          - normal palette lookup
                COLORMODE_HAM8          - HAM8 mode palette lookup
                COLORMODE_HAM6          - HAM6 mode palette lookup
                
                Default - COLORMODE_CLUT.

        RND_DitherMode (UWORD) - Error diffusion mode. Valid types:

                DITHERMODE_NONE   - no error diffusion

                DITHERMODE_FS     - Floyd-Steinberg
                                    Does not handle a dither amount.

                DITHERMODE_RANDOM - Random dithering
                                    Handles RND_DitherAmount.

                DITHERMODE_EDD    - EDD dithering
                                    Does not handle a dither amount.

                Default - DITHERMODE_NONE.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_OffsetColorZero (UWORD) - First pen number to appear
                in the rendered chunky image. This offset will be
                added to the palette's indices. Default - 0.
                Note: RND_PenTable overrides RND_OffsetColorZero.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.
                Note: RND_PenTable overrides RND_OffsetColorZero.

        RND_LineHook (ULONG) - Pointer to a callback hook structure
                for line-related operations during render. This hook
                is executed once before a line is rendered and once
                after it has been completed. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_DitherAmount (UWORD) - Dither intensity (0-255).
                Only valid with certain dither modes (see above).
                Default - 128.

        RND_ScaleEngine (ULONG) - Pointer to a scaling-engine.
                This scaling-engine will be used to scale the
                source data stream before it is being rendered.
                Default - NULL.

                Notes: 
                - The scaling engine's destination width and
                  height specifications override the width and
                  height arguments for RenderA().
                - The scaling-engine must have been created with
                  PIXFMT_0RGB_32.

        RND_MapEngine (ULONG) - Pointer to a mapping-engine.
                This can greatly improve render performance.
                Default - NULL.
                
                Notes:
                - Mapping-engines are not applied for rendering
                  to HAM modes.
                - With dithering enabled, you better do not
                  specify a mapping-engine which was created with
                  a link to a histogram. Accurate conversion could
                  not be guaranteed in this case.

@{b}   RESULTS@{ub}
        success - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  REND_SUCCESS.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_RENDERED message type.

@{b}   SEE ALSO@{ub}
        @{"MapRGBArrayA()" Link "MapRGBArrayA()"}, @{"ConvertChunkyA()" Link "ConvertChunkyA()"}, @{"CreateMapEngineA()" Link "CreateMapEngineA()"},
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "RGBArrayDiversityA()" "render.library/RGBArrayDiversityA"

@{b}   NAME@{ub}
        RGBArrayDiversityA - calculate RGB array adaptibility
        RGBArrayDiversity  - varargs stub for RGBArrayDiversityA

@{b}   SYNOPSIS@{ub}
        diversity = RGBArrayDiversityA(rgbarray,width,height,taglist)
        d0                             a0       d0    d1     a1

        LONG RGBArrayDiversityA(ULONG *,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        LONG RGBArrayDiversity(ULONG *,UWORD,UWORD,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function calculates a RGB array's adaptibility to a palette
        or mapping-engine.

@{b}   INPUTS@{ub}
        rgbarray - pointer to an array of RGB data
        width    - width of the RGB array [pixels]
        height   - height of the RGB array [pixels]
        taglist  - pointer to an array of tagitems

@{b}   TAGS@{ub}
        RND_Palette (ULONG) - pointer to a palette. Either this or the
                RND_MapEngine argument is obligatory!

        RND_MapEngine (ULONG) - pointer to a mapping-engine. Either this
                or the RND_Palette argument is obligatory!

        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_Interleave (ULONG) - number of pixels to skip horizontally.
                Default - 0.

@{b}   RESULTS@{ub}
        diversity - an indicator for the RGB array's adaptibility to
                    the given palette or mapping-engine. 0 indicates
                    perfect adaptibility, 195075 indicates the worst
                    case.

@{b}   IMPLEMENTATION   @{ub}
        Every RGB in the source array is adapted to the specified
        palette or mapping-engine. Now assume p2 is the RGB of the
        palette entry that matches best with the requested RGB p1.

            R
            |
            |      * p2
            |     /
            |    /
            |   / d
            |__/_________G
           /  /
          /  * p1
         /
        B

        This function sums up the diversity d² for every RGB in the
        source array, and divides it by the number of pixels processed:

                          k=pixels
                  1         ___
        D   =   ------   .  \\  `   d(k)²
                pixels      /__,

                             k=1

        D is returned, so what you get is the average d² for all RGB
        values that appear in the array. d² is summed up instead of d
        because it is a better indicator for most purposes.

        Best case - all pixels match perfectly: D(min) = 0.
        Worst case - all pixels are white, and the only available color
        in the palette is black: D(max) = 255²+255²+255² = 195075.
        
@{b}   EXAMPLE        @{ub}
        D indicates a palette's applicability for the given RGB array.
        You can e.g. use it to decide whether error diffusion should be
        enabled or not.

        dithermode = DITHERMODE_NONE;

        D = RGBArrayDiversity(rgbarray, width, height, 
            RND_Palette, destpalette, RND_Interleave, 4, TAG_DONE);

        if (D > threshold)
        {
            dithermode = DITHERMODE_FS;
        }

        Render(rgbarray, width, height, chunkyarray, destpalette,
            RND_DitherMode, dithermode, TAG_DONE);

        The interleave factor increases speed drastically. Nonetheless,
        RGBArrayDiversity() is yet very fast. You gain a lot of
        performance if only dithering can be avoided sometimes.

        Applying RGBArrayDiversity() to a mapping-engine is even more
        sophisticated. Use this if a histogram is available for the RGB
        array.

        me = CreateMapEngine(palette,RND_Histogram,histo,TAG_DONE);

        D = RGBArrayDiversity(rgbarray, width, height, 
            RND_MapEngine, me, RND_Interleave, 4, TAG_DONE);

        if (D > threshold)
        {
            Render(rgbarray, width, height, chunkyarray, destpalette,
                RND_DitherMode, DITHERMODE_FS, TAG_DONE);
        }
        else
        {
            MapRGBArray(me, rgbarray, width, height, chunkyarray, NULL);
        }

        This example provides even higher performance. @{"MapRGBArrayA()" Link "MapRGBArrayA()"} is
        faster than @{"RenderA()" Link "RenderA()"}, especially when the mapping-engine is
        coupled with a histogram. Note: That mapping-engine's histogram
        has to be of a HSTYPE_..._TURBO type with the same resolution as
        the palette.

@{b}   SEE ALSO@{ub}
        @{"ChunkyArrayDiversityA()" Link "ChunkyArrayDiversityA()"}


@EndNode

@Node "ScaleA()" "render.library/ScaleA"

@{b}   NAME@{ub}
        ScaleA - scale an image.
        Scale  - varargs stub for ScaleA.

@{b}   SYNOPSIS@{ub}
        success = ScaleA(engine,source,dest,taglist)
                         a0     a1     a2   a3
        
        ULONG ScaleA(APTR,APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG Scale(APTR,APTR,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function scales a source array of pixels to another
        array.

@{b}   INPUTS@{ub}
        engine  - pointer to a scaling-engine created
                  with @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}
        source  - pointer to source array of pixels
        dest    - pointer to destination array
        taglist - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the source array [pixels].
                Default - equals to the source width the scaling-engine
                          was created with.

        RND_DestWidth (UWORD) - Total width of the dest array [pixels].
                Default - equals to the destination width the
                          scaling-engine was created with.

        RND_LineHook (ULONG) - Pointer to a callback hook structure
                for line-related operations during conversion. This
                hook is executed once before a line is processed and
                once after it has been completed. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

@{b}   RESULTS@{ub}
        success - CONV_SUCCESS to indicate that the operation
                  succeeded. Currently, the only reason for this
                  function to fail is CONV_CALLBACK_ABORTED.

@{b}   NOTES@{ub}
        - It is possible to downscale (shrink) an array over itself,
          i.e. source and destination buffers may be the same in this
          case.

@{b}   SEE ALSO@{ub}
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}, @{"RenderA()" Link "RenderA()"}, @{"ConvertChunkyA()" Link "ConvertChunkyA()"}


@EndNode

@Node "ScaleOrdinate()" "render.library/ScaleOrdinate"

@{b}   NAME@{ub}
        ScaleOrdinate - scale a single ordinate.

@{b}   SYNOPSIS@{ub}
        scaled_ordinate = ScaleOrdinate(start,dest,ordinate)
        d0                              d0    d1   d2

        UWORD ScaleOrdinate(UWORD,UWORD,UWORD)

@{b}   FUNCTION@{ub}
        This function scales a single ordinate. The algorithm used here
        is identical to what scaling-engines are created with.
        
@{b}   INPUTS@{ub}
        start    - original value (e.g. width or height)
                   e.g. the original width of an image.
                   This value usually corresponds to a
                   start value with @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}.
                   Must not be 0.
        dest     - destination value (e.g. width or height)
                   e.g. the scaled width of an image.
                   This value usually corresponds to a
                   dest value with @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}.
                   Must not be 0.
        ordinate - a single ordinate (e.g. of a pixel).
                   Must be less than <start>.

@{b}   RESULTS@{ub}
        scaled_ordinate - the new ordinate (after scaling)
        
@{b}   EXAMPLE        @{ub}
        Assume you have a specific pair of coordinates that represent a
        particular pixel inside an image. You can use this function to
        determine the pixel's new coordinates after the image has been
        scaled:

        new_pixel_x = ScaleOrdinate(picwidth,newwidth,pixel_x);
        new_pixel_y = ScaleOrdinate(picheight,newheight,pixel_y);

@{b}   SEE ALSO@{ub}
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}


@EndNode

@Node "SortPaletteA()" "render.library/SortPaletteA"

@{b}   NAME@{ub}
        SortPaletteA - sort a palette.
        SortPalette  - varargs stub for SortPaletteA.

@{b}   SYNOPSIS@{ub}
        success = SortPaletteA(palette,mode,taglist)
        d0                     a0      d0   a1
        
        ULONG SortPaletteA(APTR,ULONG,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG SortPalette(APTR,ULONG,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Sorts a palette according to a sort mode. Some sort modes apply
        to palettes solely, some others additionally require a
        histogram.

@{b}   INPUTS@{ub}
        palette - pointer to a palette created
                  with @{"CreatePaletteA()" Link "CreatePaletteA()"}.

        mode    - sort mode. Currently defined are:

                  PALMODE_BRIGHTNESS      - sort the palette entries
                                by brightness.

                  PALMODE_SATURATION      - sort the palette entries
                                by their color intensity.

                  PALMODE_POPULARITY      - sort the palette entries
                                by the number of pixels that they
                                represent. You must specify the
                                RND_Histogram taglist argument.

                  PALMODE_REPRESENTATION  - sort the palette entries
                                by the number of histogram entries
                                that they represent. You must specify
                                the RND_Histogram taglist argument.
                  
                  PALMODE_SIGNIFICANCE    - sort the palette entries
                                by their optical significance for the
                                human eye. Implementation is unknown
                                to you and may change. You must supply
                                the RND_Histogram taglist argument.

                  PALMODE_ASCENDING       - by default, sort direction
                                is descending, i.e. precedence is
                                `more-to-less' of the given effect.
                                Combine with this flag to invert the
                                sort direction.

        taglist - pointer to an array of tagitems.

@{b}   TAGS@{ub}
        RND_Histogram (ULONG) - pointer to a histogram. This taglist
               argument is obligatory for some sort modes. (See above)

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for SORTP_SUCCESS.

@{b}   NOTES@{ub}
        SortPaletteA() can be extremely useful when a palette is to be
        allocated from a @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} via @{"ObtainBestPenA()" Link "graphics/ObtainBestPenA()"}. After sorting
        with PALMODE_SIGNIFICANCE, important colors will be treated
        first. This increases probability for @{"ObtainBestPenA()" Link "graphics/ObtainBestPenA()"} to
        allocate new pens for the most significant entries in the
        palette.


@EndNode

@Node "TintRGBArrayA()" "render.library/TintRGBArrayA"

@{b}   NAME@{ub}
        TintRGBArrayA - tint an RGB array.
        TintRGBArray  - varargs stub for TintRGBArrayA.

@{b}   SYNOPSIS@{ub}
        TintRGBArrayA(sourcearray,width,height,RGB,ratio,destarray,tags)
                      a0          d0    d1     d2  d3    a1        a2

        void TintRGBArrayA(ULONG *,UWORD,UWORD,ULONG,UWORD,ULONG *,
                           struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        void TintRGBArray(ULONG *,UWORD,UWORD,ULONG,UWORD,ULONG *,
                          tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function mixes an RGB array with the specified RGB
        value and a mixing ratio. The result is written to another
        array, which may be the same as the source array.

@{b}   INPUTS@{ub}
        sourcearray         - pointer to an ARGB array
        width               - width [pixels]
        height              - height [rows]
        RGB                 - tint RGB
        ratio               - tint ratio (0...255)
        destarray           - pointer to an ARGB array
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the source array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the dest array [pixels].
                Default - equals to the specified width.

@{b}   RESULTS@{ub}
        none


@EndNode

